This file is best viewed in SimpleText or TextEdit. It contains an exact copy of the help available from within Analog Helper, however in this format it can be viewed separately, or printed.
Introduction and Help
Analog Helper is a graphical configuration tool for Analog which is a free program to analyze the logfiles from your web server. Analog Helper lets you control and preview the results of hundreds of settings and automatically takes care of the complex syntax of Analog╒s configuration files.
Analog itself was written by Stephen Turner and ported to Mac by Jason T. Linhart. It reports which pages are most popular, which countries people are visiting from, which sites they followed links from and many other valuable statistics. It is the fastest and most flexible such tool available.
Analog Helper can also configure Report Magic (a free Analog add-on from Wadsack-Allen) for more advanced HTML reporting, automatically configuring Analog to output data for Report Magic, writing Report Magic╒s config file and running Report Magic. However, this entire process is transparent ╨ once the analysis is configured as required, Analog Helper will do the rest of the work.
Analog Helper can also import any existing Analog configuration files to provide an easy way to adjust existing setups. But Analog Helper also extends Analog╒s functionality by allowing multiple configurations to be maintained, integrating Report Magic and optionally splitting analyses up into separate daily, weekly, monthly or annual reports.
Analog Helper contains context-sensitive help which can be toggled from the Help menu for all available options. Analog Helper also contains more detailed help, available from the Help menu. For details on Analog itself, please read the HTML documentation in the docs folder which comes with the Analog download.
We hope you find Analog Helper useful. If there are any comments or suggestions, please contact us at comment@sigsoftware.com
Sig Software
http://www.sigsoftware.com/
Payment, Registration and Upgrading
Analog Helper is freely distributed as trial software. You are permitted to evaluate it for 28 days before discarding it, or purchasing a license. When Analog Helper is purchased, all of the output reports will be enabled.
Licensing
You must purchase one license for each computer on which Analog Helper is used. Licenses can be purchased with the enclosed Register Analog Helper program, using a page on the World Wide Web, or via telephone. Payment may be made by cash, check, VISA, MasterCard or American Express.
Pricing
Current pricing is $39 for a single-CPU license. Upgrades from versions of Analog Helper prior to 1.5 cost $14. There is excellent discount pricing available for multiple-license purchases; the Register Analog Helper application includes pricing for up to 20 licenses - for higher-volume pricing, please contact us at sales@sigsoftware.com.
Purchasing online (easiest)
Ñ Click Purchase Online╔ in the about box or go to http://order.kagi.com/?BX
Ñ Wait for your web browser to load up the page.
Ñ Select how many of which products you wish to purchase.
Ñ Enter your name, address and email address in the areas provided (all are required).
Ñ Please enter any additional comments in the space provided.
Ñ Follow the instructions on the web page to enter your credit-card details.
Purchasing via email
Ñ Click Purchase Alternative╔ in the about box or run the Register Analog Helper program.
Ñ Enter your name, address and email address in the areas provided (all are required).
Ñ Select how many of which products you wish to purchase.
Ñ Please enter any additional comments by clicking the speech bubble next to the product name.
Ñ Select the VISA, MasterCard or American Express payment method and enter your card details.
Ñ Click the Copy╔ button to copy out the text for emailing.
Ñ Create a new email message in your email software.
Ñ Choose Paste from the Edit menu.
Ñ Address the message to shareware@kagi.com and send it.
Purchasing over the telephone
Ñ Call (US) 510 658-5244, available 10am to 5pm PST weekdays and at some other times.
Ñ Follow the instructions on the telephone.
Ñ When asked, specify how many, of which products you wish to purchase.
Ñ When asked, state your name, address and email address clearly (all are required).
Ñ Please note that telephone orders carry an additional handling charge of $5.
Purchasing via fax
Ñ Click Purchase Alternative╔ in the about box or run the Register Analog Helper program.
Ñ Enter your name, address and email address in the areas provided (all are required).
Ñ Select how many of which products you wish to purchase.
Ñ Please enter any additional comments by clicking the speech bubble next to the product name.
Ñ Select the VISA, MasterCard or American Express payment method and enter your card details.
Ñ Click the Print╔ button to print out the form for faxing.
Ñ Fax the printed form to (US) 510 652-6589.
Purchasing by mail (slowest)
Ñ Click Purchase Alternative╔ in the about box or run the Register Analog Helper program.
Ñ Enter your name, address and email address in the areas provided (all are required).
Ñ Select how many of which products you wish to purchase.
Ñ Please enter any additional comments by clicking the speech bubble next to the product name.
Ñ Select the Check, Cash, VISA, MasterCard or American Express payment method.
Ñ If you are purchasing by cash, select the currency you wish to pay in.
Ñ If you are purchasing by credit-card, enter your card details.
Ñ Click the Print╔ button to print out the form to sent with your payment.
Ñ Send to: Kagi, 1442-A Walnut St PMB #392-BX, Berkeley, CA 94709-1405, USA.
After you have purchased
Shortly after your payment has been processed by Kagi, you will automatically receive an email with the subject Thanks for your Payment containing an enabler code which will work for 7 days. During this period you will be emailed your permanent license code or contacted if there is a problem (a human has to check your details before sending a permanent license). If you wish to trace an order, please contact license@sigsoftware.com.
Getting Started with Analog Helper
To start using Analog Helper, either use the blank analysis that comes up when it is opened or import a previous .cfg file using the Import command in the File menu. On the left is a list of panels of options that can be edited. The first three contain global settings for an analysis, described in the next section. Each of the others represents one of the reports that Analog can produce and are described in a separate help section.
To actually perform an analysis, click the Analyze button or hit return. To only write Analog╒s analog.cfg config file without performing the analysis, click Write Config. The analysis can be performed later by running Analog manually. The On Open menu lets you set which action Analog Helper should perform on the analysis file when it is opened from the Finder. To stop this happening when the file is opened, hold down any modifier key (shift, option, command, control) or open the analysis from within Analog Helper by choosing Open from the File menu.
The Use Nav Services setting in the Edit menu controls whether files and folders should be chosen using Apple╒s Navigation Services (included in Mac OS 8.5 but available for OS 7.5.5 or later.) Navigation Services have been known to cause problems with some setups, so switch this setting off if you are experiencing any.
Inputs Files, Output Report, Filters and Commands
Input Files
This panel is mainly for setting which log files Analog should analyze. Add individual files or entire folders of files (with sub-folders included) to this list using drag-and-drop or by clicking the Add File / Folder button. Log files within a selected folder can also be filtered by name or last modified date.
This panel also contains other options, described by context-sensitive help. If multiple reports are being created using the Create Reports option, the Date from value (and optionally the Date to) should also be set, otherwise Analog Helper will have to make a sensible, but probably wrong, guess of the overall time period to analyze.
Note: if you switch on domain name lookups in the Domain name mode menu, be aware that analyses will probably take at least 10 times longer than otherwise.
Output Report
This panel contains various options connected to the final report file, which can be in Text Only, Basic HTML, Advanced HTML or Computer-readable format. The panel displays an explanation of each of these options. Set the Report Out File to the name and location you want. The Viewing Program sets which program the final report should belong to and therefore what it will be opened in if Open after Analysis is on.
For Basic HTML reporting, the Image File Prefix is a relative path from the output report location to the directory containing the images required by the report. Ensure you have a copy of the relevant files (depending on your choice of bar style and PNG setting) from Analog╒s images folder in this location, otherwise graph bars and other pictures will appear as broken images (if in doubt, just copy across the entire folder╒s contents). If you want to use Analog╒s pie chart feature, the Chart File Prefix is a relative path to the directory where chart image files should be created.
For Advanced HTML reporting, the two .gif files in Report Magic╒s folder should be copied to the directory specified by the Image File Prefix, although you can leave this blank to automatically have them copied into the required location.
Filters and Commands
This panel contains several filter lists under Filter log entries by (see next section for how all such lists are interpreted). These allow an analysis to be performed on only a part of the requests made to the web site, based on many different types of criteria.
The Analog Commands list allows any additional commands to be written out directly at the end of Analog╒s configuration file. This allows access to any Analog features that Analog Helper cannot configure graphically and also allows any other settings to be overridden. The Magic Commands list does the same thing for Report Magic, allowing each additional command to be assigned to the correct section of the Report Magic .ini file.
Include / Exclude Rule Lists
All Include / Exclude rule lists are interpreted in the same manner. The order of the rules in the list does make a difference,and the algorithm applied is as follows: To decide whether an item should be included, the last rule that matches the item is used. If, however, the item matched none of the rules, it is included if the first rule was an Exclude, and excluded if the first rule was an Include. Here is an example:
(1) Include: A*
(2) Exclude: *N*
(3) Include: G*
For this rule list, the following items would be included: ALPHA (matches 1), GAMMA (matches 3), GAIN (matches 2, 3). The following items would be excluded: BETA (matches none, so excluded since first rule was an Include), AGAIN (matches 1, 2), NAG (matches 2).
As demonstrated above, the * character can be used as a wild card in a rule and it will match any series of zero or more characters. For example, the rule A*ND* would match AND, ABANDON and ANDES. In relevant rule lists, the keyword pages can also be used to refer to all page files.
Lastly, for several of the reports, a Sub Rule (or Sub-Include) can also be added. These are used in hierarchical reports ╨ see the next section for more details.
Reports and Graphs
The reports to be output can be switched on and off by clicking on the check or cross to the right of the name of the report. The reports may also be reordered by dragging vertically. Each report contains a different set of relevant options ╨ all possibilities are listed here below (in alphabetical order):
Ñ Add Include / Exclude. Click one of these buttons to add a rule to determine which rows are shown in the report. See the previous section for help on using rule lists. Note: the Normal limit setting may still exclude a row that would be included based on the rule list.
Ñ Add Sub Rule. In hierarchical reports, the sub-items to be shown as separate rows in the report may be chosen. A sub rule might be a sub-directory, a sub-domain, a sub-file type or a sub-browser. Wild cards can be used here as in other rules. Note: the Sub-row limit setting may still exclude a row that would be included based on the rule list.
Ñ Argument limit. This specifies the limit on which argument rows should be shown in the report (i.e. where a separate row is shown with an URL╒s arguments). It works in the same way as Normal limit ╨ see that section for more information.
Ñ Columns. This pop-up menu allows columns to be displayed or hidden in the report╒s graph. Note: not every column will be available for every report type.
Ñ Draw pie chart. This specifies whether a pie chart graphic should be produced for this report. The image will be created in a GIF file in the directory determined by the Chart File Prefix setting in the Output Report panel.
Ñ Graph by. This specifies which statistic the graph bars (shown in red in the Sample) should be based on.
Ñ Maximum number of rows. This specifies a maximum number of rows to show in the graph.
Ñ Normal limit. This specifies the limit on which rows should be shown in the report. It can be based on a minimum number of pages, bytes or requests, a minimum percentage of the total pages, bytes or requests or a minimum percentage of the row with the most pages, bytes or requests. For these three options, Analog Helper will automatically pick (and show) whether it will use pages, bytes or requests depending on the Sort by setting. There are also options to specify a simple maximum number of rows to include or to include rows which have a last or first access date in a specified range.
Ñ Sample. This is an example of the report╒s output, based on random fictional data, as it would appear in a Basic HTML report. Columns within the Sample area can be dragged to reorder - use the Columns menu to add or remove columns. The Sample area will not show the include / exclude rule list or limits being applied, however it does show the result of the Columns, Graph by, Sort backwards and Sort by settings.
Ñ Sort backwards. This toggles whether a report should have the order of its rows reversed.
Ñ Sort by. This specifies the method which should be used for sorting the rows of the report. This setting may also affect the limit settings.
Ñ Sub-row limit. This specifies the limit on which sub-rows should be shown in the report (i.e. where a separate row is shown for a sub-directory, sub-browser, etc...). It works in the same way as Normal limit ╨ see that section for more information.
Frequently Asked Questions
What version of Analog does Analog Helper require?
Analog Helper needs version 3.0 of Analog or later. It will automatically display an alert if a copy of this is not found on any mounted disk. This version of Analog Helper also fully supports Analog 4 and 5. If you are using Analog 3 or 4, some of the configuration options will be ignored.
What can I do with my old .cfg files?
Analog Helper can import these, using Import from the File menu. A few of the lines in a config file may not be imported ╨ a full summary of the import operation will be displayed upon completion. Information can be dragged out of this report onto the desktop as a clipping file.
Why can╒t Analog Helper important all the lines of my .cfg files?
A few commands in Analog config files are overridden or configured differently in Analog Helper. These include the SUBSORTBY commands (which Analog Helper automatically maps to the non-hierarchical setting), input and output files (which Analog Helper stores references to in its own way) and warning and debug settings (which Analog Helper sets automatically).
How do I manage multiple virtual domains?
This depends on how your web server is configured to write the logs for the separate domains. If it actually records the virtual host as a separate field in log files, use the Virtual Host filter list in the Filters and Commands panel.
However, if it logs requests in made-up directories to mimic the different virtual domains, use the Requested file filter list in the Filters and Commands panel to only include requests from the desired virtual domain. (In this case, also add a Sub-Rule to the directory report to include the real directories on your web site inside the made-up directories).
What about configuration commands Analog Helper doesn╒t support?
In the Filters and Commands panel, any extra commands can be added in the Analog Commands section. These will be written at the end of the analog.cfg file.
What about other languages?
Analog Helper supports all the languages that can be accessed using the LANGUAGE command for version 4.1. If you want to use a different language or a langfile, add the command manually in the Analog Commands section of the Filters and Commands panel.
Will I lose my current analog.cfg file?
No. Analog Helper is very careful not to overwrite the current analog.cfg file unless it was created by Analog Helper itself. If an analog.cfg file was found by Analog Helper which it had to remove, the file will have been renamed analog.cfg.old and will be in its original location.
What happens with manconf.cfg?
As before, Analog will automatically read the manconf.cfg file after it has read the configuration set up by Analog Helper. So manconf.cfg can still be used to contain overriding settings or lists of aliases.
Are aliases supported?
Analog Helper does not currently support graphical configuration of input or output aliases (which allow certain values to be mapped to others in order to group them or make them more readable). However, aliases will not be lost when importing a .cfg file and will be added to the Analog Configuration section of the Filters and Commands panel. It is recommended to place aliases into the manconf.cfg file which Analog always reads last to ensure they are accessible to all your configurations.
How does multiple report generation work?
If one of the options from the Create Reports menu of the Input Files panel is chosen, Analog Helper will automatically step through all the specified time periods, generating a separate output report file for each one. These will be named as the Report File in the Output Report panel, prefixed with the relevant date.
How do I edit an Analog Helper file without it automatically analyzing?
Hold down one of the modifier keys (shift, command, option, control) when opening the file or open it by choosing Open from the File menu instead of from the Finder. Once the file is open, automatic analysis can be switched off using the On Open menu at the bottom of the configuration window.
How can I set up Analog Helper for scheduling?
Scheduling is not built-in to the current version of Analog Helper. However, to set up a scheduled analysis, simply use some other scheduling program (e.g. CRON) to open the Analog Helper analysis file at the required intervals. If the Analog Helper analysis file is set to Analyze automatically, it will perform the analysis every time it is opened.
How can I include or exclude whole directories in my report?
In the Requested file section of the Filters and Commands panel, enter rules such as Include: /pub/* or Exclude: /private/*.
Why does Analog Helper not work with the Report Magic Perl script on OS X?
In order to co-ordinate effectively with other stages in the analysis process, Analog Helper requires certain features of the Mac-specific build of Report Magic. Please download and use that version.
⌐ Sig Software ╤ http://www.sigsoftware.com/
Any distribution of Analog Helper must include this file. No responsibility about Analog Helper╒s functionality or integrity is implied. This document and Analog Helper are copyright of the author. Other trademarks are copyright of their respective owners.
